OSStatus AEBuildDesc(
    AEDesc* dst,
    AEBuildError* error,  /* NULL の場合もある */
    const char* src,
    ...);

パラメータ：

• dst - 作成するディスクリプタを保存する AEDesc レコードへのポインタ。
  
  
• error - 発生するすべてのエラーに関する詳細情報が保存される AEBuildError 構造体へのポインタ。このパラメータは省略可能であり、この情報が必要なければ、代わりに NULL を渡しても構いません。
  
  
• src - 作成する AEDesc レコードについて記述する AEBuild 書式指定文字列。
  
  
• ... - src パラメータに渡す書式指定文字列が必要とする任意の数のパラメータ。
  
  

結果：
AEBuildDesc の呼び出しの成否を数値で表す結果コード。値 AEBuildSyntaxNoErr（ゼロ）は、呼び出しの成功を意味します。error パラメータを使えば、ほかのエラーに関する情報を知ることができます。

typedef UInt32 AEBuildErrorCode;

struct AEBuildError {
    AEBuildErrorCode fError;
    UInt32 fErrorPos;
};
typedef struct AEBuildError AEBuildError;

表 1　 AEBuild の拡張エラーコード

OSStatus vAEBuildDesc(
    AEDesc* dst,
    AEBuildError* error,  /* NULL の場合もある */
    const char* src,
    va_list args);

パラメータ：

• dst - 作成するディスクリプタを保存する AEDesc レコードへのポインタ。
  
  
• error - 発生するすべてのエラーに関する詳細情報が保存される AEBuildError 構造体へのポインタ。このパラメータは省略可能であり、この情報が必要なければ、代わりに NULL を渡しても構いません。
  
  
• src - 作成する AEDesc レコードについて記述する AEBuild の書式指定文字列。
  
  
• args - vAEBuildDesc に使用される任意の長さの引数リストを参照する va_list。
  
  

結果：
AEBuildDesc の呼び出しの成否を数値で表す結果コード。値 AEBuildSyntaxNoErr（ゼロ）は、呼び出しの成功を意味します。error パラメータを使えば、ほかのエラーに関する情報を知ることができます。

OSStatus AEBuildAppleEvent(
    AEEventClass theClass,
    AEEventID theID,
    DescType addressType,
    const void* addressData,
    long addressLength,
    short returnID,
    long transactionID,
    AppleEvent* result,
    AEBuildError* error,    /* NULL の場合もある*/
    const char* paramsFmt,
    ...);

注意：AEBuildAppleEvent には、vAEBuildAppleEvent という varargs と同等の関数があります。

パラメータ：

• theClass - 作成するアップルイベントのイベントクラス。
  
  
• theID - 作成するアップルイベントのイベント ID。
  
  
• addressType - 次の 2 つのパラメータに記述するアドレス情報のアドレスタイプ。通常は、typeApplSignature、typeProcessSerialNumber、またはtypeKernelProcessID のどれかです。
  
  
• addressData - アドレス情報へのポインタ。
  
  
• addressLength - addressData パラメータが指すデータのバイト数。
  
  
• returnID - 通常は、値 kAutoGenerateReturnID に設定されます。詳細については Apple Event Manager に関する文献を参照してください。
  
  
• transactionID - 通常は、値 kAnyTransactionID に設定されます。詳細については Apple Event Manager に関する文献を参照してください。
  
  
• result - 作成されたディスクリプタが保存される AEDesc レコードへのポインタ。
  
  
• error - 発生するすべてのエラーに関する詳細情報が保存される AEBuildError 構造体へのポインタ。このパラメータは省略可能であり、この情報が必要なければ、代わりに、値 NULL を渡しても構いません。
  
  
• paramsFmt - 作成する AppleEvent レコードについて記述する AEBuild の書式指定文字列。
  
  
• ... - paramsFmt パラメータに渡す書式指定文字列が必要とする任意の数のパラメータ。
  
  

結果：
AEBuildDesc の呼び出しの成否を数値で表す結果コード。値 AEBuildSyntaxNoErr （ゼロ）は、呼び出しの成功を意味します。error パラメータを使えば、ほかのエラーに関する情報を知ることができます。

重要：
アップルイベントレコードにあるダイレクトパラメータの識別子は、4 個のマイナス記号（'----'）です。このマイナス記号は、AEBuild 文字列では特別な意味を持ち、ディスクリプタ文字列の中でアップルイベントのダイレクトパラメータを指すために使う場合は、必ず単一引用符で囲まなければなりません。

リスト 1　 AEBuildAppleEvent ルーチンを使った、［Open Documents］アップルイベント作成方法の例

AliasHandle first_file, second_file;
const OSType finderSignature = 'MACS';
AppleEvent event;
OSErr err;
FSRef file1ref;
FSSpec file2spec;

    /* エイリアスを作成する...*/
err = FSNewAlias(NULL, &file1ref, &first_file);
if (err == noErr) {

  err = NewAlias(NULL, &file2spec, &second_file);
  if (err == noErr) {

    err = AEBuildAppleEvent(
        kCoreEventClass, kAEOpenDocuments,
        typeApplSignature, &finderSignagure, sizeof(finderSignature),
        kAutoGenerateReturnID, kAnyTransactionID,
        &event,   /* 作成するイベント */
        NULL,   /* エラー情報を必要としない */
        "'----':[alis(@@), alis(@@)]", /* 書式指定文字列 */
        first_file, /* 1 番目の @@ に対応するパラメータ */
        second_file); /* 2 番目の @@ に対応するパラメータ */

OSStatus AEBuildParameters(
    AppleEvent* event,
    AEBuildError* error, /* NULL の場合もある */
    const char* format,
    ...);

注意：AEBuildParameters は、vAEBuildParameters という名前の varargs に相当する関数を持っています。

パラメータ：

• event - 新規パラメータを追加する対象となる AppleEvent レコードへのポインタ。
  
  
• error - 発生するすべてのエラーに関する詳細情報が保存される AEBuildError 構造体へのポインタ。このパラメータは省略可能であり、この情報が必要でなければ、代わりに、値 NULL を渡しても構いません。
  
  
• format - 追加する AppleEvent パラメータを記述する AEBuild の書式指定文字列。
  
  
• ... - format パラメータで渡す書式指定文字列が必要とする任意の数のパラメータ。
  
  

結果：
AEBuildParameters の呼び出しの成否を数値で表す結果コード。値 AEBuildSyntaxNoErr（ゼロ）は、呼び出しの成功を意味します。error パラメータを使えば、その他のエラーに関する情報を知ることができます。

OSStatus AEPrintDescToHandle(
    const AEDesc* desc,
    Handle* result);

パラメータ：

• desc - 出力するアップルイベントディスクリプタレコードへのポインタ。
  
  
• result - ディスクリプタ文字列を含む、新規に作成されたメモリマネージャ 'Handle' の格納場所へのポインタ。
  
  

結果：
AEPrintDescToHandle の呼び出しの成否を数値で表す結果コード。値 AEBuildSyntaxNoErr（ゼロ）は、呼び出しの成功を意味します。

[ "Mac OS X", 'null'(), 44]

aevt¥odoc{ ----:"Mac OS X",
           &addr:psn ($0000000000040001$),
           &subj:'null'(),
           &csig:magn($00010000$) }

表 2 AEBuild の基本データタイプ

重要：
カンマ、括弧、中括弧、末尾以外でのスペースなどの特殊文字を含むコード、または - のような特殊文字で始まるタイプコードには注意します。これらの文字は、AEBuild では構文の一部として使用されます。タイプコードでこれらの特殊文字を使う必要がある場合は、そのタイプコードを単一引用符で囲みます。

        <希望のタイプコード> ( <任意のデータタイプ> )

  sing(123)
  type(line)
  hexd("a string")
  'blob'($4170706C65$)
  'utxt'($0048 0045 004C  004C 004F$)

  null()
  'null'()
  ()

        [ <ディスクリプタ>, <ディスクリプタ>... ]

[123, -456, "et cetera"]
[sing(1234), long(CODE)]
[["wheels", "within wheels"]]
[sing(1234), long(CODE), [[123, -456, "et cetera"], "within wheels"]]
[]

        { <名前> : <値>, <名前> : <値>... }

        <タイプコード> { <名前> : <値>, <名前> : <値>... }

{x: 100, y:-100}
{'origin': {x: 100, y:-100}, extent: {x: 500, y:500},
   cont: [1, 5, 25]}
{}
rang{ star: 5, stop: 6}

 rang{ star: 5, stop: 6}

リスト 2 AEDesc レコードを書式付きで出力するための gdb スクリプト

define aedesc
  call (void *) malloc(4)
  set $aed_malloc=$
  call (long) AEPrintDescToHandle($arg0, $aed_malloc)
  if $ == 0
    printf "desc @ %p = {¥n    type = '%.4s'¥n    storage (%p) = %s¥n}¥n", ¥
      $arg0, $arg0, ((long *) $arg0)[1], **(char ***) $aed_malloc
    call (void) DisposeHandle(*(char ***) $aed_malloc)
  else
    printf "aedesc failed: error %d.¥n", $
  end
  call (void) free($aed_malloc)
end

リスト 3　 簡単なスクリプト

tell application "Finder"
    activate
    open "Mac OS X"
end tell

リスト 4　 gdb セッションログ

    ## Terminal ウィンドウで、gdb を開始する
[neithermac:/] apple% gdb
GNU gdb 5.0-20001113 (Apple version gdb-203) ([....] GMT 2001) (UI_OUT)
Copyright 2000 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you
are welcome to change it and/or distribute copies of it under certain
conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "powerpc-apple-macos10".


    ## 自分の aedesc スクリプトを読み込む。通常は、「source」と入力し、その後
    ## このスクリプトのファイルアイコンを Terminal ウィンドウにドラッグアンドドロップする。
    ## ただし、このスクリプトを自分の gdb 設定に追加することも可能（「man gdb」を参照）
    ## スクリプトは、ディスクリプタを書式付きで出力するための 
    ## AEPrintDescToHandle の呼び出しに使えるコマンド、'aedesc' を定義する
(gdb) source /Users/apple/gdb-aedesc

    ## 次にスクリプトエディタのプロセスにアタッチする
    ## このプロセスは、gdb セッションの前に作成した 1312 というプロセスの ID を持つ。
    ## 実行プロセスのプロセス ID は、「top -l」または「ps -aux」を使って
    ## を調べることができる
(gdb) attach 1312
Reading symbols for shared libraries . done
Reading symbols for shared libraries ..................................
.................... done
[Switching to process 1312 thread 0x1603]

    ## その後、AESend にブレークポイントを設定して、出力イベントをトラップできるようにする
(gdb) break AESend
Breakpoint 1 at 0x731ddbec

    ## また、スクリプトエディタによる実行の継続を許可するように gdb に指示する
(gdb) continue
Continuing.

    ## ここで、スクリプトエディタを使って、元に戻る
    ## スクリプトを実行するために「run」ボタンをクリックする


    ## イベント送信時に停止
Breakpoint 1, 0x731ddbec in AESend ()

    ## スクリプトにディスクリプタを書式付きで出力するように要求する（$r3 を使用）
(gdb) aedesc $r3
$1 = (void *) 0x1bb8310
$2 = 0
desc @ 0xbfffe398 = {
    type = 'aevt'
    storage (0x150d858) = misc¥actv{ &addr:psn ($0000000000040001$),
                  &subj:'null'(), &csig:magn($00010000$) }
}

    ## また、スクリプトエディタによる実行の継続を許可するように gdb に指示する
(gdb) continue
Continuing.

    ## ［Open Documents］イベントで停止 
Breakpoint 1, 0x731ddbec in AESend ()

    ## ディスクリプタを書式付きで出力するようにスクリプトに要求する（$r3 を使用）
(gdb) aedesc $r3
$3 = (void *) 0x16ea1c0
$4 = 0
desc @ 0xbfffe2c8 = {
    type = 'aevt'
    storage (0x150d858) = aevt¥odoc{ ----:"Mac OS X",
                  &addr:psn ($0000000000040001$), &subj:'null'(),
                  &csig:magn($00010000$) }
}

    ## また、スクリプトエディタによる実行の継続を許可するように gdb に指示する
(gdb) continue
Continuing.

# 注意：構文規則の間に挿入されたコメントの前には # 文字が置かれる
# これらのコメントは、BNF ではない

# AEBuildAppleEvent の構文規則
AEBuild-apple-event-expression ::= <event-keyword-list>

# event-keyword-list - 0 個以上のイベント/キーワードのペアのリスト
# カンマにより区切られる
event-keyword-list ::= <event-keyword-pair> , <event-keyword-list>
event-keyword-list ::= <event-keyword-list>
event-keyword-list ::=

# event-keyword-pair 識別子/オブジェクトのペア
# このペアの前には、省略可能なパラメータであることを示すチルド記号、‾ が置かれる
event-keyword-pair ::= ‾ <identifier> : <object>
event-keyword-pair ::= <identifier> : <object>


#AEBuildDesc の構文規則
AEBuild-expression ::= <object>

object ::= <data>                    # Single AEDesc; （データ）のショートカット
object ::= <structure>               # タイプ変換されていない構造体
object ::= <identifier> <structure>  # cほかのタイプに変換される

structure ::= ( <data> )             # 1 つの AEDesc
 structure ::= [ <object-list> ]      # AEDescList タイプ
structure ::= { <keyword-list> }     # AERecord タイプ

# 0 個以上の、カンマで区切られたオブジェクトのリスト
object-list ::= <object-list> , object>
object-list ::= <object>
object-list ::=

# 0 個以上の、カンマで区切られたキーワード/値のペアのリスト
keyword-list ::= <keyword-list> , <keyword-pair>
keyword-list ::= <keyword-pair>
keyword-list ::=
keyword-pair ::= <identifier> : <object>  # keyword/value pair


# @ と @@ は、ディスクリプタの作成時に、
# ディスクリプタに AEBuild パラメータを読み込むために使用する特別な記号
data ::= @             # AEBuild パラメータからデータを読み込む
data ::= @@            # AEBuild ハンドルのパラメータからデータを読み込む
data ::= <integer>     # タイプ変換されていなければ、'shor' タイプまたは 'long' タイプ
data ::= <identifier>  # タイプ変換されていなければ、4 文字のタイプコード（'type'）
data ::= <string>      # タイプ変換されていなければ、ヌルで終了されないテキスト（'TEXT'）
data ::= <hex-string>  # 未加工の 16 進数のデータ。何らかのタイプに変換する必要がある！
data ::=               # 空のヌルのデータ。null() によるタイプ変換に有効

integer ::= - <number>
integer ::= <number>
number ::= <number> <digit>
number ::= <digit>
digit ::= 0 .. 9

# 単一引用符で囲まれていない場合には、識別子の中に
# スペースを含めることはできない
# 識別子は、ちょうど 4 文字になるように、AEBuild およびその関連ルーチンにより、 
# スペースが埋め込まれるか、切り捨てが行われる
identifier ::= <first-ident-letter> <ident-letter-list>
identifier ::= ' <any-letter letter-list> '   # straight quotes (preferred)
identifier ::= ‘ <any-letter letter-list> ‘   # curly quotes
ident-letter-list ::= <ident-letter-list> <ident-letter>
ident-letter-list ::= <ident-letter>
ident-letter-list ::=
first-ident-letter ::= alphabetic characters

# AEBuild 言語の特殊文字は、識別子の中に含めることはできない
# 特殊文字を含む識別子を使用するには、
# その識別子を単一引用符で囲む
ident-letter ::= any printable character excluding spaces
                 and special AEBuild characters

string ::= " <letter-list> "     # 直線状の二重引用符（推奨）
string ::= “ <letter-list> ”     # カール状の二重引用符
letter-list ::= <letter-list> <any-letter>
letter-list ::= <any-letter>
letter-list ::=
any-letter ::= any printable character including spaces
               and special AEBuild characters.

# 16 進数の場合は、数字の間に空白文字を含めることができる
# したがって書式を整えるために自由に空白文字を追加できる
hex-string ::= $ <hex-digit-list> $   # ドル記号の引用符（推奨）
hex-string ::= « <hex-digit-list> »   #フランス語の引用符
hex-digit-list ::= <hex-digit-list> <hex-digit-pair>
hex-digit-list ::= <hex-digit-pair>
hex-digit-list ::=
hex-digit-pair ::= <hex-digit> <hex-digit>
hex-digit ::= digits 0 .. 9 or letters A .. F （大文字小文字は無視される）